home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / public / patch / README.SGI < prev    next >
Text File  |  1994-08-01  |  11KB  |  247 lines
  1.  
  2.                            toolbox/public/patch
  3.  
  4.  
  5.     Often, software updates (especially for public domain packages such as 
  6.     GNU) are distributed in the form of context diffs.
  7.  
  8.     The "patch" utility will automagically insert the contents of the diff 
  9.     file into the original source.
  10.  
  11.     This package is being re-distributed as received from the Free Software 
  12.     Foundation, which in turn was received from Larry Wall 
  13.     (lwall@netlabs.com).  Anyone may distribute this freely, as long as you 
  14.     abide by the restrictions contained in the README file.
  15.  
  16.     The Makefile and the patch executable (built on IRIX 4.0.4) are 
  17.     included here.  The Makefile generated by the "Configure" script was 
  18.     modified to use SGI's "install" utility.  To install the patch 
  19.     executable and the man page onto your IRIS workstation without 
  20.     recompiling, execute:
  21.  
  22.         su
  23.         ./install.patch
  24.  
  25.     If you wish to recompile patch, copy this entire directory to a local 
  26.     disk, and execute make.  If you encounter a problem and wish to rebuild 
  27.     the configuration, remove "Makefile", "config.h", and "config.sh".  
  28.     Then run the "Configure" script and rerun make (or "make install").
  29.  
  30.     A copy of the man page follows.
  31.     
  32.     
  33.     ----------------------------------------------------------------
  34.     
  35.     
  36.     PATCH(1)            UNIX Programmer's Manual             PATCH(1)
  37.     
  38.     NAME
  39.          patch - a program for applying a diff file to an original
  40.     
  41.     SYNOPSIS
  42.          patch [options] orig diff [+ [options] orig]
  43.     
  44.     DESCRIPTION
  45.          Patch will take a patch file containing any of the three
  46.          forms of difference listing produced by the diff program and
  47.          apply those differences to an original file, producing a
  48.          patched version.  By default, the patched version is put in
  49.          place of the original, with the original file backed up to
  50.          the same name with the extension ".orig", or as specified by
  51.          the -b switch.  You may also specify where you want the out-
  52.          put to go with a -o switch.  If diff is omitted, or is a
  53.          hyphen, the patch will be read from standard input.
  54.     
  55.          Upon startup, patch will attempt to determine the type of
  56.          the diff file, unless over-ruled by a -c, -e, or -n switch.
  57.          Context diffs and normal diffs are applied by the patch pro-
  58.          gram itself, while ed diffs are simply fed to the ed editor
  59.          via a pipe.
  60.     
  61.          Patch will try to skip any leading garbage, apply the diff,
  62.          and then skip any trailing garbage.  Thus you could feed an
  63.          article or message containing a context or normal diff to
  64.          patch, and it should work.  If the entire diff is indented
  65.          by a consistent amount, this will be taken into account.
  66.     
  67.          With context diffs, and to a lesser extent with normal
  68.          diffs, patch can detect when the line numbers mentioned in
  69.          the patch are incorrect, and will attempt to find the
  70.          correct place to apply each hunk of the patch.  As a first
  71.          guess, it takes the line number mentioned for the hunk, plus
  72.          or minus any offset used in applying the previous hunk.  If
  73.          that is not the correct place, patch will scan both forwards
  74.          and backwards for a set of lines matching the context given
  75.          in the hunk.  All lines of the context must match.  If patch
  76.          cannot find a place to install that hunk of the patch, it
  77.          will put the hunk out to a reject file, which normally is
  78.          the name of the output file plus ".rej".  (Note that the
  79.          rejected hunk will come out in context diff form whether the
  80.          input patch was a context diff or a normal diff.  If the
  81.          input was a normal diff, many of the contexts will simply be
  82.          null.)
  83.     
  84.          If no original file is specified on the command line, patch
  85.          will try to figure out from the leading garbage what the
  86.          name of the file to edit is.  In the header of a context
  87.          diff, the filename is found from lines beginning with "***"
  88.          or "---", with the shortest name of an existing file win-
  89.          ning.  Only context diffs have lines like that, but if there
  90.          is an "Index:" line in the leading garbage, patch will try
  91.          to use the filename from that line.  The context diff header
  92.          takes precedence over an Index line.  If no filename can be
  93.          intuited from the leading garbage, you will be asked for the
  94.          name of the file to patch.
  95.     
  96.          (If the original file cannot be found, but a suitable SCCS
  97.          or RCS file is handy, patch will attempt to get or check out
  98.          the file.)
  99.     
  100.          Additionally, if the leading garbage contains a "Prereq: "
  101.          line, patch will take the first word from the prerequisites
  102.          line (normally a version number) and check the input file to
  103.          see if that word can be found.  If not, patch will ask for
  104.          confirmation before proceeding.
  105.     
  106.          The upshot of all this is that you should be able to say,
  107.          while in a news interface, the following:
  108.     
  109.               | patch -d /usr/src/local/blurfl
  110.     
  111.          and patch a file in the blurfl directory directly from the
  112.          article containing the patch.
  113.     
  114.          If the patch file contains more than one patch, patch will
  115.          try to apply each of them as if they came from separate
  116.          patch files.  This means, among other things, that it is
  117.          assumed that separate patches will apply to separate files,
  118.          and that the garbage before each patch will be examined for
  119.          interesting things such as filenames and revision level, as
  120.          mentioned previously.  You can give switches (and another
  121.          original file name) for the second and subsequent patches by
  122.          separating the corresponding argument lists by a '+'.  The
  123.          argument list for a second or subsequent patch may not
  124.          specify a new patch file, however.
  125.     
  126.          Patch recognizes the following switches:
  127.     
  128.          -b   causes the next argument to be interpreted as the
  129.               backup extension, to be used in place of ".orig".
  130.     
  131.          -c   forces patch to interpret the patch file as a context
  132.               diff.
  133.     
  134.          -d   causes patch to interpret the next argument as a direc-
  135.               tory, and cd to it before doing anything else.
  136.     
  137.          -D   causes patch to use the "#ifdef...#endif" construct to
  138.               mark changes.  The argument following will be used as
  139.               the differentiating symbol.  Note that, unlike the C
  140.               compiler, there must be a space between the -D and the
  141.               argument.
  142.     
  143.          -e   forces patch to interpret the patch file as an ed
  144.               script.
  145.     
  146.          -l   causes the pattern matching to be done loosely, in case
  147.               the tabs and spaces have been munged in you input file.
  148.               Any sequence of whitespace in the pattern line will
  149.               match any sequence in the input file.  Normal charac-
  150.               ters must still match exactly.  Each line of the con-
  151.               text must still match a line in the input file.
  152.     
  153.          -n   forces patch to interpret the patch file as a normal
  154.               diff.
  155.     
  156.          -N   forces patch to not try and reverse the diffs if it
  157.               thinks that they may have been swapped.  See the -R
  158.               option below.
  159.     
  160.          -o   causes the next argument to be interpreted as the out-
  161.               put file name.
  162.     
  163.          -p   causes leading pathnames to be kept.  If the diff is of
  164.               the file "b/a.c", patch will look for "a.c" in the "b"
  165.               directory, instead of the current directory.  This
  166.               probably won't work if the diff has rooted pathnames.
  167.     
  168.          -r   causes the next argument to be interpreted as the
  169.               reject file name.
  170.     
  171.          -R   tells patch that this patch was created with the old
  172.               and new files swapped.  (Yes, I'm afraid that does hap-
  173.               pen occasionally, human nature being what it is.) Patch
  174.               will attempt to swap each hunk around before applying
  175.               it.  Rejects will come out in the swapped format.  The
  176.               -R switch will not work with ed diff scripts because
  177.               there is too little information to reconstruct the
  178.               reverse operation.
  179.     
  180.               If the first hunk of a patch fails, patch will reverse
  181.               the hunk to see if it can be applied that way unless
  182.               the -N option is supplied.  If it can, the -R switch
  183.               will be set automatically.  If it can't, the patch will
  184.               continue to be applied normally.  (Note: this method
  185.               cannot detect a reversed patch if it is a normal diff
  186.               and if the first command is an append (i.e. it should
  187.               have been a delete) since appends always succeed.
  188.               Luckily, most patches add lines rather than delete
  189.               them, so most reversed normal diffs will begin with a
  190.               delete, which will fail, triggering the heuristic.)
  191.     
  192.          -s   makes patch do its work silently, unless an error
  193.               occurs.
  194.     
  195.          -x<number>
  196.               sets internal debugging flags, and is of interest only
  197.               to patch patchers.
  198.     
  199.     ENVIRONMENT
  200.          No environment variables are used by patch.
  201.     
  202.     FILES
  203.          /tmp/patch*
  204.     
  205.     SEE ALSO
  206.          diff(1)
  207.     
  208.     DIAGNOSTICS
  209.          Too many to list here, but generally indicative that patch
  210.          couldn't parse your patch file.
  211.     
  212.          The message "Hmm..." indicates that there is unprocessed
  213.          text in the patch file and that patch is attempting to
  214.          intuit whether there is a patch in that text and, if so,
  215.          what kind of patch it is.
  216.     
  217.     CAVEATS
  218.          Patch cannot tell if the line numbers are off in an ed
  219.          script, and can only detect bad line numbers in a normal
  220.          diff when it finds a "change" command.  Until a suitable
  221.          interactive interface is added, you should probably do a
  222.          context diff in these cases to see if the changes made
  223.          sense.  Of course, compiling without errors is a pretty good
  224.          indication that it worked, but not always.
  225.     
  226.          Patch usually produces the correct results, even when it has
  227.          to do a lot of guessing.  However, the results are
  228.          guaranteed to be correct only when the patch is applied to
  229.          exactly the same version of the file that the patch was gen-
  230.          erated from.
  231.     
  232.     BUGS
  233.          Could be smarter about partial matches, excessively deviant
  234.          offsets and swapped code, but that would take an extra pass.
  235.     
  236.          If code has been duplicated (for instance with #ifdef OLD-
  237.          CODE ... #else ...  #endif), patch is incapable of patching
  238.          both versions, and, if it works at all, will likely patch
  239.          the wrong one, and tell you it succeeded to boot.
  240.     
  241.          If you apply a patch you've already applied, patch will
  242.          think it is a reversed patch, and un-apply the patch.  This
  243.          could be construed as a feature.
  244.     
  245.     Printed 12/10/87          May 10, 1986                          4
  246.     
  247.